home *** CD-ROM | disk | FTP | other *** search
/ Aminet 5 / Aminet 5 - March 1995.iso / Aminet / dev / c / agl103p.lha / src / agl / agl.doc next >
Text File  |  1994-12-08  |  12KB  |  325 lines
  1. *******************************************************************************
  2.  
  3.                                What is AGL?
  4.  
  5.                          Amiga GL by Jason Weber
  6.                          Copyright © 1994, Jason Weber
  7.  
  8. This library is a subset of the IrisGL(TM) graphics language.  IrisGL(TM) was
  9. developed by Silicon Graphics Inc (SGI) (TM).  The Amiga version presented
  10. here is not produced, supported, or endorsed by SGI(TM).  SGI's (TM) unoffical
  11. release of their API allows me to release my Amiga version to the general
  12. public.
  13.  
  14. This software was produced using IrisGL(TM) user manuals and experience on
  15. SGI(TM) systems.  No source was obtained or used from the original SGI(TM)
  16. source.  The goal of this library is total upwards compatibility to a
  17. compliant platform.
  18.  
  19. The user should obtain documents which explain the use of IrisGL(TM).
  20. There are no lessons, tutorials, or texts included in this release.
  21. I recommend the "Graphics Library Programming Guide" distributed by SGI(TM).
  22.  
  23.  
  24.                               DISCLAIMER:
  25.  
  26. This version of IrisGL(TM) non-compliant and unlicensed.  It bears no
  27. guarantee of fitness for any particular purpose.  The user assumes all
  28. responibilty for any actions or damage resulting from its use.  Many
  29. significant parts of the real IrisGL(TM) specification have not been
  30. included in this release.
  31.  
  32. This library provides an introduction to the IrisGL(TM) graphics language
  33. and is not intended for serious or commercial use.  Serious parties should
  34. seek to purchase a compliant licensed version of IrisGL(TM) or OpenGL(TM) on
  35. an acceptable platform.
  36.  
  37.  
  38. I presume Silicon Graphics Inc., SGI, IrisGL, and OpenGL are trademarks
  39. of Silicon Graphics Inc.
  40.  
  41. *******************************************************************************
  42.  
  43.                         Who would do such a thing?
  44.  
  45. This source/library is property of Jason Weber.  Before the official release,
  46. you must obtain permission to use this software by contacting:
  47.  
  48.                              Jason Weber
  49.                           403 Montpelier Dr.
  50.                           Stafford, VA 22554
  51.  
  52. No one is permitted to distribute a modified version of this software without
  53. permission.  Any redistribution must contain all of the original files.  Any
  54. fix or improvement must be passed through the original author.
  55.  
  56. There is no fee to copy the software.  Permission to use is only granted to
  57. users who register the software.  This allows me to maintain contact and gives
  58. me incentive to make repairs and improvements.  You should send the following
  59. to the address above:
  60.  
  61. Name
  62. Address
  63. Occupation
  64. What you are using the software for
  65. e-mail address
  66. $20 registration fee
  67.  
  68. If you truly can not afford the fee, you still register without it by adding
  69. the following line to your registration: "I can afford all this computer
  70. equipment, but I can't afford to support the work of fellow programmers".
  71. If you have written a public domain or shareware program that I am using
  72. (Vim, Csh, KingCON, HWGRCS, Enforcer, CPUblit, fASTERbliT, MagicMenus,
  73. MagicWB, Toolmanager, VMM), state this and we can just call it even.
  74.  
  75. *******************************************************************************
  76.  
  77.                       What hardware/software does it need?
  78.  
  79. The library's source can be compiled for any Amiga.  I believe I followed all
  80. the "rules" and avoided any tempting tricks.  The given library was compiled
  81. for 68030 with coprocessor under SAS 6.51.  Check "scopts" to see how it
  82. was compiled so that your code will match.
  83.  
  84. I use a 25Mhz Amiga 3000.  I would recommend this as a minumum configuration.
  85. The performance is poor on a stock Amiga 500.
  86.  
  87. The compile scripts use csh (Csh 5.37 by Urban D Mueller/Andreas M Kirchwitz).
  88.  
  89. The middle mouse button is fully supported.  If you don't have a middle mouse
  90. button, it is very unlikely that you will receive a MIDDLEMOUSE event.
  91.  
  92. *******************************************************************************
  93.  
  94.                             What does it consist of?
  95.  
  96. The following files, at least, should be included in this archive.  I may have
  97. submitted the precompiled library separately or not at all.  Except for the
  98. font, all these directories/files should be placed in a directory assigned
  99. to "usr:".
  100.  
  101.  
  102. The library:
  103.  
  104.   libs/
  105.     gl.lib
  106.  
  107. My font:
  108.  
  109.   fonts/
  110.     JXEN/7
  111.     JXEN.font
  112.  
  113.  
  114. The required headers:
  115.  
  116.   include/
  117.     gl.h
  118.     device.h
  119.  
  120.  
  121. Some utilities:
  122.  
  123.   bin/
  124.     basename     (executable; replaces csh's incorrect builtin version)
  125.     prototype    (executable; my auto-prototyper)
  126.  
  127.  
  128. The source:
  129.  
  130.   src/basename
  131.     basename.c
  132.  
  133.   src/prototype
  134.     prototype.c
  135.  
  136.   src/agl
  137.     prototypes.h (will be generated automatically by 'prototype')
  138.  
  139.     agl.doc      (you're reading it)
  140.  
  141.     keymap.h
  142.     agl.h
  143.  
  144.     border.c     (Motif(TM) style borders)
  145.     clip.c       (scrmask clipping using Regions)
  146.     matrix.c     (transforms)
  147.     poly.c       (primary drawing)
  148.     que.c        (event handling)
  149.     rgb.c        (auto-dithering for RGBmode())
  150.     text.c       (text drawing)
  151.     window.c     (window handling)
  152.  
  153.     mice.c       (test to read second mouse, not really used)
  154.     sprite.c     (test to draw second mouse, not really used)
  155.  
  156.     makefile
  157.     Compile
  158.     sas.makefile
  159.  
  160.     RCS/         (revision control)
  161.  
  162.  
  163. Sample code:
  164.  
  165.   src/gltest
  166.     gltest.c
  167.  
  168.  
  169. "usr:bin" should be added to your path.  Note that this not enough to
  170. override csh's builtin incorrect "basename" which has to be aliased.
  171. The Compile script for AGL does this alias to make sure.
  172.  
  173. You should also copy the font into your fonts: or AGL will use your default
  174. system font.  The JXEN font is a reduced version of XEN from MagicWB by
  175. Martin Huttenloher.  I believe JXEN 7 to be the smallest readable
  176. fixed-space font.  I use it for my shells.
  177.  
  178. *******************************************************************************
  179.  
  180.                             What is supported?
  181.  
  182.  
  183. CONFIGURATION
  184.   gversion(), getgdesc(), getdisplaymode()
  185.  
  186. WINDOWS
  187.  
  188.   foreground()
  189.   prefposition(), prefsize()
  190.   winopen(), winclose(), winset(), winget(), winpush(), winpop()
  191.   winposition(), winmove(), wintitle()
  192.   getsize(), getorigin()
  193.   singlebuffer(), doublebuffer(), swapbuffers()
  194.   cmode()
  195.   RGBmode(): EXPERIMENTAL
  196.   gconfig()
  197.  
  198. EVENTS
  199.  
  200.   getbutton() for keys and mouse buttons
  201.   getvaluator() for MOUSEX,MOUSEY
  202.  
  203.   qdevice(), unqdevice(), isqueued(), qreset()
  204.   qenter(), qtest(), qread()
  205.  
  206.   tie() to mouse valuators
  207.  
  208.   queue-able events: REDRAW, INPUTCHANGE, MOUSEX, MOUSEY,
  209.                      LEFTMOUSE, MIDDLEMOUSE, RIGHTMOUSE,
  210.                      KEYBD, WINQUIT, most individual keys
  211.  
  212. TRANSFORMS
  213.  
  214.   perspective(), ortho2(), ortho()
  215.   scrmask(), viewport()
  216.   pushmatrix(), popmatrix()
  217.   translate(), rot(), scale()
  218.   mmode(), getmmode(), loadmatrix(), getmatrix(), multmatrix()
  219.  
  220. DRAWING
  221.  
  222.   mapcolor(), getmcolor(), color(), getcolor()
  223.   clear()
  224.   bgnpoint(), endpoint(), bgnline(), endline(), bgnpolygon(), endpolygon()
  225.   v2i(), v3i(), v2s(), v3s(), v2f(), v3f()
  226.   cmov2s(), cmovs(), cmov2i(), cmovi(), cmov2(), cmov(),
  227.   charstr(), getcpos()
  228.   recti(), rectfi(), rects(), rectfs(), rect(), rectf()
  229.  
  230.  
  231. Check in prototypes.h to see if a specific function is supported.  Note that
  232. there are many non-IrisGL(TM) support functions in there as well.  None of
  233. those should be called directly from the user's software.
  234.  
  235. *******************************************************************************
  236.  
  237.                    What may be supported in the future?
  238.  
  239. auto-dithered RGBmode()
  240. OpenGL(TM) compatibility
  241. a 24-bit graphics board
  242. pop-up menus
  243.  
  244. *******************************************************************************
  245.  
  246.                         What is not supported?
  247.  
  248. zbuffer()
  249. lighting
  250. shading
  251. texture mapping
  252.  
  253. *******************************************************************************
  254.  
  255.         How else does AGL differ from real IrisGL(TM) on an SGI(TM)?
  256.  
  257.  
  258. 1.  A single solitary optional Amiga-specific function is included to
  259. configure the screen:
  260.  
  261.       long AGLconfig(short screenx,short screeny,short bitplanes)
  262.         returns nonzero if successful
  263.  
  264. If used, this call must be made before any GL call or it will have no effect
  265. and just return 0.  It specifies the size and depth of the screen.  AGL will
  266. automatically use hi-res laced if either dimension exceeds a specific level.
  267. The actual screen created may be different than what the user requested.  The
  268. function getgdesc() should be used to get the actual values for the screen.
  269.  
  270. 2.  If there are multiple windows in the application, window-independent
  271. double-buffering is simulated using a blit copy from a backbuffer.
  272. If there is only one window, true double buffering (of the screen) is used.
  273.  
  274. 3.  Interactive window placement is not supported and all programs are run in
  275. the foreground.  A warning is issued if foreground() doesn't precede the first
  276. window opening.
  277.  
  278. 4.  Intuition uses a structure "Device".  Therefore, the IrisGL(TM) typedef
  279. of "Device" is intentionally removed.  You should use "long" instead to refer
  280. to IrisGL(TM) devices.
  281.  
  282. 5.  AGL is run on a separate screen that is created automatically on your first
  283. winopen().  It is closed automatically when you winclose() your last window.
  284.  
  285. 6.  Intuition does not have a window auto-kill and cleanup like on an SGI(TM).
  286. A sudden break (like CTRL-C) may leave the windows and memory in use.  Your
  287. program should issue a qdevice(WINQUIT) to que the close gadget and close all
  288. your windows when it is done.  AGL automatically shuts down when the final
  289. window is closed.  As an added precaution, AGL uses the ANSI atexit() function
  290. to shut down automatically during an exit(), hopefully.  However, you should
  291. not rely on this as it is not clean programming practice.
  292.  
  293. 7.  You should use AutoPoint and ClickToFront to act more like the SGI(TM).
  294. There will be a slight difference from the SGI(TM) in that a window will
  295. retain focus even after the mouse is moved out and until another window is
  296. selected.  This should only be a problem in that the middle and right buttons
  297. may report outside the window.
  298.  
  299. 8.  AGL has its own built-in window borders that should look and act similarly
  300. to Motif(TM) as one would have under IRIX(TM) 4.0.X and beyond, including the
  301. Maximize button.  However, the upper left menu button does not produce a menu,
  302. but immediately enters WINQUIT onto the que.  The Minimize button does nothing
  303. at this time.
  304.  
  305. 9.  MagicMenus by Martin Korndorfer is highly recommended.  This would
  306. actually be relevant if I were to add pop-up menus.
  307.  
  308. 10.  Intuition can sometimes send double Refresh's resulting in double
  309. REDRAW's.  If you read through the entire queue at once, you can eliminate
  310. redundancy by only redrawing once.
  311.  
  312. 11. I cannot directly poll the mouse buttons for getvaluator().  Instead,
  313. I update a value on every message from intuition.  (Intuition messages all
  314. give the current mouse button state)  The noticable difference is that when
  315. a no AGL window is focused,  the AGL program gets no messages and, therefore,
  316. the mouse button state is not updated.  The key states are done similarly,
  317. except that they are only updated on key events.
  318.  
  319. 12. I've made no effort to implement the obsolete MSINGLE matrix mode even
  320. though it's the default.  The user should always call mmode(MVIEWING) or
  321. mmode(MPROJECTION) before doing matrix operations.  AGL will just use
  322. MVIEWING when in MSINGLE mode, but this may not (should not) be the case when
  323. ported to another platform.  MTEXTURE mode is not supported.
  324. *******************************************************************************
  325.